package interfaces.app;

import exceptions.StreamEOFException;
import exceptions.StreamException;

/**
 * A stream representing an output or an input.
 * <br/>
 * Created: 11.10.11
 *
 * @author Martin Štulc (<a href="mailto:martin.stulc@gmail.com">martin.stulc@gmail.com</a>)
 * @version 1.0
 */
public interface IStream
{
    /**
     * Return true if the stream is opened.
     *
     * @return true if the stream is opened; otherwise false
     */
    boolean isOpen();

    /**
     * Return true if the stream is opened exclusively.
     *
     * @return true if the stream is opened exclusively; otherwise false
     */
    boolean isExclusive();

    /**
     * Open the stream, if no possible return false.
     *
     * @param accessAttribute access to the stream; 1=read; 2=write
     * @return true if opening was successful; otherwise false
     */
    boolean tryOpen(final int accessAttribute);

    /**
     * Open the stream, if no possible then wait.
     *
     * @param accessAttribute access to the stream; 1=read; 2=write
     * @throws StreamException Thrown if occurs error during opening of the stream.
     */
    void open(final int accessAttribute) throws StreamException;

    /**
     * Close the stream.
     *
     * @throws StreamException if stream can not be closed
     */
    void close() throws StreamException;

    /**
     * Read a line from the stream if can not read wait.
     *
     * @return the line from stream
     * @throws StreamException    Thrown if occurs error during reading.
     * @throws StreamEOFException Thrown if occurs EOF on input.
     */
    String readLine() throws StreamException, StreamEOFException;

    /**
     * Write a line to the stream.
     *
     * @param line a line
     * @throws StreamException Thrown if occurs error during writing into stream.
     */
    void writeLine(final String line) throws StreamException;

    /**
     * Notify all waiting process.
     */
    void notifyAllProcess();

    /**
     * Set the exclusivity.
     *
     * @param exclusive the exclusivity
     */
    void setExclusive(final boolean exclusive);
}
